
package com.uuah.server.api.transport;

import com.uuah.exception.AbstractUuahException;
import com.uuah.server.api.endpoint.IUuahEndpoint;

/**
 *  <code>MessageDispatcherFactory</code> is a factory interface for managing
 * the lifecycles of a transport's message dispatchers. The methods basically
 * implement the {@link org.apache.commons.pool.KeyedPoolableObjectFactory}
 * lifecycle, with a {@link IUuahEndpoint} as the key and the dispatcher as
 * pooled object.
 *
 * <p>update record:updator，update time，update content and version</p>
 * @author <a href="jonny_quan@hotmail.com">jonny</a>
 * @date 2009 2009-3-27 上午12:13:01
 * @version 1.0.0
 */
public interface IMessageDispatcherFactory {

	/**
	 * Controls whether dispatchers are cached or created per request. Note that
	 * if an exception occurs in the dispatcher, it is automatically disposed of
	 * and a new one is created for the next request. This allows dispatchers to
	 * recover from loss of connection and other faults. When invoked by
	 * {@link #validate(IUuahEndpoint, IMessageDispatcher)} it takes precedence
	 * over the dispatcher's own return value of
	 * {@link IMessageDispatcher#validate()}.
	 *
	 * @return true if created per request
	 */
	boolean isCreateDispatcherPerRequest();

	/**
	 * Creates a new message dispatcher instance, initialised with the passed
	 * endpoint. The returned instance should be immediately useable.
	 *
	 * @param endpoint
	 *            the endoint for which this dispatcher should be created
	 * @return a properly created <code>MessageDispatcher</code> for this
	 *         transport
	 * @throws AbstractUuahException
	 *             if the dispatcher cannot be created
	 */
	IMessageDispatcher create(IUuahEndpoint endpoint) throws AbstractUuahException;

	/**
	 * Invoked <strong>before</strong> the given dispatcher is handed out to a
	 * client, but <strong>not</strong> after {@link #create(IUuahEndpoint)}.
	 *
	 * @param endpoint
	 *            the endpoint of the dispatcher
	 * @param dispatcher
	 *            the dispatcher to be activated
	 * @throws AbstractUuahException
	 *             if the dispatcher cannot be activated
	 */
	void activate(IUuahEndpoint endpoint, IMessageDispatcher dispatcher)
			throws AbstractUuahException;

	/**
	 * Invoked <strong>after</strong> the dispatcher is returned from a client
	 * but <strong>before</strong> it is prepared for return to its pool via
	 * {@link #passivate(IUuahEndpoint, IMessageDispatcher)}.
	 *
	 * @param endpoint
	 *            the endpoint of the dispatcher
	 * @param dispatcher
	 *            the dispatcher to be validated
	 * @return <code>true</code> if the dispatcher is valid for reuse,
	 *         <code>false</code> otherwise.
	 */
	boolean validate(IUuahEndpoint endpoint, IMessageDispatcher dispatcher);

	/**
	 * Invoked immediately <strong>before</strong> the given dispatcher is
	 * returned to its pool.
	 *
	 * @param endpoint
	 *            the endpoint of the dispatcher
	 * @param dispatcher
	 *            the dispatcher to be passivated
	 */
	void passivate(IUuahEndpoint endpoint, IMessageDispatcher dispatcher);

	/**
	 * Invoked when a dispatcher returned <code>false</code> for
	 * {@link #validate(IUuahEndpoint, IMessageDispatcher)}.
	 *
	 * @param endpoint
	 *            the endpoint of the dispatcher
	 * @param dispatcher
	 *            the dispatcher to be validated
	 */
	void destroy(IUuahEndpoint endpoint, IMessageDispatcher dispatcher);

}
